👨‍👩‍👧‍👦 API de Responsáveis - Documentação Completa

📋 Visão Geral

A API de Responsáveis é responsável por toda a gestão de responsáveis no sistema CordenaAi, incluindo cadastro, atualização, consulta, relacionamento com atletas e funcionalidades específicas como pesquisa e gerenciamento de vínculos. Esta API fornece a base para o sistema de responsabilidade legal e familiar, permitindo a associação entre responsáveis e atletas com identificadores flexíveis.

🎯 Endpoints Disponíveis

👨‍👩‍👧‍👦 Responsáveis - Gestão de Responsáveis

1. GET /api/Responsaveis

Listar Todos os Responsáveis

• Descrição: Retorna lista completa de todos os responsáveis cadastrados no sistema
• Método: GET
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros: Nenhum
• Resposta: Array de objetos ResponsavelReadDto
• Uso: Dashboard administrativo, listagem geral de responsáveis

2. POST /api/Responsaveis

Criar Novo Responsável

• Descrição: Cria um novo responsável no sistema
• Método: POST
• Autenticação: Requerida (JWT Bearer Token)
• Body: Objeto ResponsavelCreateDto
• Resposta: Objeto ResponsavelReadDto criado
• Uso: Formulários de cadastro de novos responsáveis

3. GET /api/Responsaveis/{id}

Obter Responsável por ID

• Descrição: Retorna os dados completos de um responsável específico
• Método: GET
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros:
  • id (path): ID único do responsável
• Resposta: Objeto ResponsavelReadDto completo
• Uso: Visualização de perfil individual, edição de dados

4. PUT /api/Responsaveis/{id}

Atualizar Responsável

• Descrição: Atualiza os dados de um responsável existente
• Método: PUT
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros:
  • id (path): ID único do responsável
• Body: Objeto ResponsavelUpdateDto
• Resposta: Objeto ResponsavelReadDto atualizado
• Uso: Formulários de edição de responsáveis

5. DELETE /api/Responsaveis/{id}

Excluir Responsável

• Descrição: Remove um responsável do sistema
• Método: DELETE
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros:
  • id (path): ID único do responsável
• Resposta: Status 204 (No Content)
• Uso: Remoção de responsáveis do sistema

6. GET /api/Responsaveis/{identificador}/atletas

Obter Atletas por Responsável

• Descrição: Retorna todos os atletas associados a um responsável específico
• Método: GET
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros:
  • identificador (path): ID, email, CPF ou username do responsável
• Resposta: Array de objetos AtletaReadDto
• Uso: Interface do responsável para visualizar seus atletas

7. POST /api/Responsaveis/{identificador}/atletas/{atletaIdentificador}

Adicionar Atleta ao Responsável

• Descrição: Cria vínculo entre um responsável e um atleta
• Método: POST
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros:
  • identificador (path): ID, email, CPF ou username do responsável
  • atletaIdentificador (path): ID, email, CPF ou username do atleta
• Resposta: Confirmação de vínculo criado
• Uso: Associação de atletas a responsáveis

8. DELETE /api/Responsaveis/{identificador}/atletas/{atletaIdentificador}

Remover Atleta do Responsável

• Descrição: Remove vínculo entre um responsável e um atleta
• Método: DELETE
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros:
  • identificador (path): ID, email, CPF ou username do responsável
  • atletaIdentificador (path): ID, email, CPF ou username do atleta
• Resposta: Confirmação de vínculo removido
• Uso: Desassociação de atletas de responsáveis

9. GET /api/Responsaveis/pesquisar

Pesquisar Responsáveis

• Descrição: Realiza busca de responsáveis com base em critérios específicos
• Método: GET
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros:
  • nome (query, opcional): Nome do responsável
  • tipo (query, opcional): Tipo do responsável
  • status (query, opcional): Status do responsável
• Resposta: Array de objetos ResponsavelReadDto que correspondem aos critérios
• Uso: Funcionalidade de busca e filtros avançados

🔧 Modelo de Dados

Estrutura do Responsável

{
  "id": "string",
  "nome": "string",
  "userId": "string",
  "email": "string",
  "telefone": "string",
  "cpf": "string",
  "tipo": "TipoResponsavel",
  "status": "StatusResponsavel",
  "dataCadastro": "datetime",
  "dataAtualizacao": "datetime"
}

Estrutura de Atleta Vinculado

{
  "id": "integer",
  "nome": "string",
  "userId": "string",
  "dataNascimento": "datetime",
  "sexo": "string",
  "email": "string",
  "cpf": "string"
}

Estrutura de Relação Responsável-Atleta

{
  "responsavelId": "string",
  "atletaId": "string",
  "relacaoId": "integer",
  "dataVinculacao": "datetime"
}

🔐 Autenticação e Autorização

Todos os endpoints requerem:

• JWT Bearer Token no header Authorization
• Permissões específicas baseadas no tipo de usuário:
  • Administradores: Acesso completo a todos os endpoints
  • Responsáveis: Acesso limitado aos seus próprios dados e atletas
  • Coordenadores: Acesso aos responsáveis de suas unidades/turmas

📊 Casos de Uso Principais

1. Cadastro de Responsável

POST /api/Responsaveis
Content-Type: application/json
Authorization: Bearer {token}

{
  "nome": "Maria Silva",
  "userId": "user-123",
  "email": "[email protected]",
  "telefone": "(11) 99999-9999",
  "cpf": "123.456.789-00",
  "tipo": "Mae",
  "status": "Ativo"
}

2. Busca de Atletas por Responsável

GET /api/Responsaveis/[email protected]/atletas
Authorization: Bearer {token}

3. Vincular Atleta ao Responsável

POST /api/Responsaveis/[email protected]/atletas/joao.silva
Authorization: Bearer {token}

4. Pesquisa Avançada

GET /api/Responsaveis/pesquisar?nome=Maria&tipo=Mae&status=Ativo
Authorization: Bearer {token}

5. Atualização de Dados

PUT /api/Responsaveis/resp-456
Content-Type: application/json
Authorization: Bearer {token}

{
  "nome": "Maria Silva Santos",
  "telefone": "(11) 88888-8888"
}

⚠️ Validações e Regras de Negócio

Validações Obrigatórias

• Nome: Obrigatório, mínimo 2 caracteres
• UserId: Obrigatório, deve existir no sistema de usuários
• Email: Formato válido, único no sistema
• CPF: Formato válido, único no sistema
• Tipo: Deve ser um valor válido do enum TipoResponsavel

Regras de Negócio

• Identificadores Flexíveis: Suporte a busca por ID, email, CPF ou username
• Vínculos: Um atleta pode ter múltiplos responsáveis
• Status: ativo, inativo, pendente
• Auditoria: Todas as operações são logadas
• Soft Delete: Responsáveis inativados não são excluídos permanentemente

🚨 Tratamento de Erros

Códigos de Status HTTP

• 200: Sucesso
• 201: Criado com sucesso
• 204: Excluído com sucesso
• 400: Dados inválidos ou parâmetros incorretos
• 401: Não autorizado
• 403: Acesso negado
• 404: Responsável ou atleta não encontrado
• 409: Conflito (CPF/Email já existente)
• 500: Erro interno do servidor

Formato de Erro

{
  "error": "string",
  "message": "string",
  "details": "string",
  "timestamp": "datetime"
}

📈 Performance e Limitações

Limitações

• Paginação: Listas retornam máximo 100 registros por página
• Rate Limiting: 1000 requests por hora por usuário
• Timeout: 30 segundos por requisição
• Identificadores: Máximo 50 caracteres por identificador

Otimizações

• Cache: Dados de responsáveis são cacheados por 5 minutos
• Índices: Busca otimizada por CPF, email e nome
• Compressão: Respostas comprimidas com gzip
• Busca Flexível: Identificadores múltiplos para melhor usabilidade

🔄 Integração com Outros Módulos

Módulos Relacionados

• Usuários: Associação obrigatória via UserId
• Atletas: Vínculos através de relações
• Relações: Sistema de vínculos responsável-atleta
• Mensagens: Comunicação com responsáveis
• Comunicados: Envio de notificações

📱 Uso em Aplicações

Web App

• Dashboard administrativo de responsáveis
• Formulários de cadastro/edição
• Gestão de vínculos responsável-atleta
• Relatórios e listagens

Mobile App

• Visualização de atletas por responsável
• Notificações e mensagens
• Atualização de dados básicos
• Gestão de vínculos familiares

🛠️ Manutenção e Monitoramento

Logs Importantes

• Criação de novos responsáveis
• Vínculos e desvínculos de atletas
• Tentativas de acesso não autorizado
• Erros de validação de identificadores

Métricas Monitoradas

• Número de responsáveis cadastrados
• Taxa de sucesso das operações
• Tempo de resposta dos endpoints
• Uso de identificadores flexíveis

📚 Exemplos Práticos

Fluxo Completo de Cadastro

1. Validação de dados no backend pela própria API
2. POST /api/Responsaveis com dados validados
3. Associação automática com usuário existente
4. Envio de notificação de boas-vindas
5. Criação de perfil no sistema

Fluxo de Vínculo Responsável-Atleta

1. Busca do responsável por identificador flexível
2. Busca do atleta por identificador flexível
3. POST /api/Responsaveis/{id}/atletas/{atletaId}
4. Criação da relação no sistema
5. Confirmação do vínculo criado

Fluxo de Busca e Filtros

1. GET /api/Responsaveis/pesquisar com parâmetros
2. Aplicação de filtros no backend
3. Retorno paginado dos resultados
4. Cache dos resultados para próximas buscas

🎯 Tipos e Enums

TipoResponsavel

• Pai (1): Pai do atleta
• Mae (2): Mãe do atleta
• Avô (3): Avô do atleta
• Avó (4): Avó do atleta
• Tio (5): Tio do atleta
• Tia (6): Tia do atleta
• Outro (7): Outro tipo de responsável

StatusResponsavel

• Ativo (1): Responsável ativo no sistema
• Inativo (2): Responsável inativo
• Pendente (3): Responsável com cadastro pendente

Versão: 1.0
Última Atualização: Outubro de 2025
Responsável: Equipe de Desenvolvimento CordenaAi